/*
 * Copyright 2011 Clean GWT
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */
package com.cleangwt.uibinder.client;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import com.google.gwt.user.client.TakesValue;

/**
 * Indicates {@link TakesValue} field to be a form input.
 * 
 * @author Jess
 * @version 1.0
 * @since 1.0
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value = ElementType.FIELD)
public @interface UiInput {
  /**
   * Specify the property name of form data, it can be wrapped like 'id.serialNo'.
   * 
   * <pre>
	 * For example below :
	 * 
	 * {@literal @}UiInput(name="id.idn")
	 * String TextBox field1;
	 * {@literal @}UiInput(name="id.serialNo")
	 * String TextBox field2;
	 * {@literal @}UiInput(name="otherName")
	 * TextBox field3;
	 * {@literal @}UiInput
	 * TextBox field4;
	 * 
	 * 
	 * the part of generated codes would be :
	 * 
	 * public void setFormData(SimpleObject value){
	 * 	field1.setValue((String)value.getSimpleObject("id").get("idn"));
	 * 	field2.setValue((String)value.getSimpleObject("id").get("serialNo"));
	 * 	field3.setValue((String)value.getSimpleObject("id").get("otherName"));
	 * 	field4.setValue((String)value.get("field4));
	 * }
	 * 
	 * public void getFormData(SimpleObject value){
	 * 	value.get("id").put("idn",field1.getValue());
	 * 	value.get("id").put("serialNo",field2.getValue());
	 * 	value.get("id").put("otherName",field3.getValue());
	 * 	value.put("field4",field4.getValue());
	 * }
	 * </pre>
   * 
   * @return the property name of form data, defaults by name of ui field
   */
  String name() default "";

  /**
   * Specify a value name to determine value getter of input. The default getter is
   * {@link TakesValue#getValue()}.
   * 
   * <pre>
	 * For example below :
	 *  
	 *  {@literal @}UiInput(value="text")
	 *  DateBox field1;
	 * 
	 * the part of generated codes would be :
	 * 
	 * public void setFormData(SimpleObject value){
	 * 	field1.setText((String)value.get("field1"));
	 * }
	 * 
	 * public void getFormData(SimpleObject value){
	 * 	value.put("field1",field1.getText());
	 * }
	 * </pre>
   * 
   * @return the value name to determine value getter of input
   */
  String value() default "";
}